Skip to content

Fix how the Roman PSF is rotated to the right sky orientation - #1377

Open
rmjarvis wants to merge 13 commits into
mainfrom
roman_psf_skycoords
Open

rmjarvis wants to merge 13 commits into
mainfrom
roman_psf_skycoords

Conversation

@rmjarvis

Copy link
Copy Markdown
Member

When working on fitting the PSF of Roman commissioning data, I realized we have a bug in the Roman getPSF function in terms of how we rotate the PSF to sky coordinates according to how the telescope is oriented. We just apply the wcs.toWorld() function. This gets the rotation and reflection (approximately) correct, but also applies the distortion, which is wrong. The upshot of the bug is that the PSF is not properly distorted when drawn with the same WCS. This PR fixes this to just apply the orthogonal part of the WCS without the distortion (symmetric positive definite part).

However, using the WCS for this is an approximation, which is still not completely correct. The WCS can include rotation components from pixel geometry, which are not properly part of the rotation we want. It turns out the Roman ASDF files include the information we need to do this correctly. Namely the boresight direction and the position angle of the V3 axis. So I also added the option to provide these directly, which does the more correct rotation. The rotation angle can still change slightly across the field of view, due to the direction to north changing slightly. But any other rotation in the WCS will be applied correctly when the object is drawn on an image.

@rmjarvis rmjarvis added bug report Bug report roman Relevant to Roman Space Telescope specifically, especially including the galsim.roman module. labels Nov 12, 2026
@rmjarvis rmjarvis added this to the v2.8 milestone Nov 12, 2026
@rmjarvis
rmjarvis force-pushed the roman_psf_skycoords branch 3 times, most recently from 3f6514e to f9e11a5 Compare November 19, 2026 06:26
@rmjarvis

rmjarvis commented Nov 19, 2026 •

Copy link
Copy Markdown
Member Author

Some updates here. I've been doing a detailed code comparison of GalSim's handling of the cycle 9 data we are currently using with how STPSF uses it, and I made a number of updates to bring GalSim in line with STPSF.

  1. We hadn't switched the focal plane orientation of some of the SCAs, so the WCS was wrong. This also impacted the aberration look ups, which use the image coordinates to get the right position in the aberration lookup table.
  2. There was a separate error in the WCS where all the non-linear terms in the SIP solution were too small by a factor of 2048. This doesn't impact the Piff work we're doing on the commissioning data, since we're using the project WCS. But it was a pretty big goof.
  3. The flip that Nihar made in Flip to WFI coords and document the flip #1363 wasn't actually correct. I think that left the image in the coordinate system looking down into the telescope, rather than looking out into the sky. So another flip was required. The two together amount to a rotation of 180 degrees, rather than just a single flip. This is equivalent to the entrance -> exit pupil discussion here https://stpsf.readthedocs.io/en/latest/STPSF_Roman_Pupil_Orientation.html. I think GalSim had been using the entrance pupil orientation and needed to rotate to the exit pupil. Rather than rotate the pupil plane, it seemed cleaner to leave it as is, since that's the frame where the aberrations are defined, and rotate the whole psf at the end.
  4. I changed the aberration interpolation to use all 5 points provided for the interpolation rather than just the 4 corners. I decided to use a different interpolation scheme than STPSF uses for this. It's a smooth polynomial across the SCA rather than piecewise linear with changes in slope at the diagonals. So there is some discrepancy still between those choices. I'm happy with my choice, and the current version agrees more closely with STPSF's treatment than the old version.
  5. We were using the default Quintic interpolant, which turned out to be not super accurate. Lanczos(15) is much more accurate for this purpose. I'm a little surprised that Quintic was the default, since I had thought our recommendation was to use Lanczos for x_interpolant and Quintic for k_interpolant, but that's not actually the case. We default to Quintic for both. I didn't open the can of worms that would be changing that across all of GalSim. I only changed it for the Roman PSF. Note -- this fixes the size issue that Federico had noticed was improved with oversampling=2. With Lanczos, this is not necessary.
  6. The last change is actually in STPSF. I found a bug in Poppy that I have a PR to fix here: Allow Zernike polynomials to continue outside radius when aperture_stop is False spacetelescope/poppy#694. Basically, they truncate the Zernike polynomials at the Zernike radius rather than continue them, even when the illumination continues past that radius. This led to significant errors in the STPSF images near the edges of the focal plane where the illumination can go outside the nominal radius. My script for comparing GalSim to STPSF monkey patches poppy with this fix.

Aside - another bug that was introduced in #1363 was the loss of the pixel scale in the pupil plane image. This caused GalSim to have to estimate it from the contents of the image, which ended up with a slightly wrong number. We don't use that function anymore for the Roman PSF, but I fixed flip_ud() and related functions to preserve the wcs of the image rather than setting it to None.

Some nice images showing the current agreement:

image image

@rmandelb

Copy link
Copy Markdown
Member

Sorry to be the peanut gallery on a minor part of this, but: your point about interpolants caught my eye.
What I had in my mind was that figure 6 of the GalSim paper https://arxiv.org/pdf/1407.7676 justifies quintic over Lanczos for the default k-interpolant for InterpolatedImages. I can't actually find a numerical test justifying a quintic default (or any default) for real space interpolant in that paper. Other refs like the Bernstein & Gruen paper also seem to focus on k-interpolant as do many of our discussions in GitHub issues about interpolants. I'm a bit mystified.

@rmjarvis
rmjarvis force-pushed the roman_psf_skycoords branch from 128444c to 0ae9fdb Compare November 19, 2026 15:09
@rmjarvis
rmjarvis changed the base branch from releases/2.8 to main November 19, 2026 15:10
@rmjarvis

rmjarvis commented Nov 19, 2026 •

Copy link
Copy Markdown
Member Author

Yeah, we have strong recommendations not to mess with the k_interpolant choice, but I remember Gary telling me that x_interpolant is basically just a user choice. It's part of the definition of what you mean by the InterpolatedImage profile. So we probably just made assumptions that Quintic was also good there, but I think the way most people intend interpolated images should be using something that approximates a sinc interpolant. Which means a Lanczos to some order.

I might make a PR changing the default to something reasonable like Lanczos 7 maybe. But not as part of this one.

BTW, these changes have edged past what I think is properly considered a bug fix, so I'll release all these with a new minor version number, 2.9.0 (once we're done getting through everything), rather than the next in the 2.8 series as I had been originally planning. As a result, I retargeted this to merge to main rather than releases/2.8.

@rmjarvis rmjarvis modified the milestones: v2.8, Version 2.9 Nov 19, 2026

@nihardalal nihardalal left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also took a look, things look overall good to me minus some documentation updates to be inline with the new coordinate system

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these changes all look good to me. Boresight and PA seem like very useful additions, and I also like the 5 point interpolation. I appreciate that the code is also a bit cleaner now (e.g. cleaning up the aberrations so that the interpolation looks cleaner)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also thanks for catching the entrance/exit pupil thing! I think we were too hyperfocused on the sign flip earlier that we missed where the pupil fit in the full picture

Comment thread galsim/roman/roman_wcs.py
@@ -94,6 +94,10 @@ def getWCS(world_pos, PA=None, date=None, SCAs=None, PA_is_FPA=False):
Cycle 6, which includes some significant updates from Cycle 5, including a 90 degree rotation of
the focal plane axes relative to the payload axes, and two rows of SCAs are swapped.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I appreciate this documentation

Comment thread galsim/roman/roman_wcs.py
@@ -137,8 +141,6 @@ def getWCS(world_pos, PA=None, date=None, SCAs=None, PA_is_FPA=False):
# Sun in the absence of a roll offset (i.e., roll offset = 0 defines the optimal position angle
# for the observatory), +Y_obs makes a right-handed system.
#

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should come up with a set of reference figures at some point, or link to the ones Chris made in PSFSim here: https://github.com/Roman-HLIS-Cosmology-PIT/PSFSim/blob/main/docs/coordinates.rst

Comment thread galsim/roman/roman_wcs.py
while shift_val > tol/coord.arcsec:
test_wcs = getWCS(fpa_cent, PA, date, use_SCA, PA_is_FPA)[use_SCA]
im_cent_pos = PositionD(n_pix/2, n_pix/2)
im_cent_pos = PositionD((n_pix+1)/2, (n_pix+1)/2)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this affect anything? I think this looks more correct than previous, and in line with how we usually center things

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really. It's slightly more correct for the 1-based image coordinates we use. But I don't think it materially matters much.

Comment thread galsim/roman/roman_wcs.py Resolved
Comment thread galsim/roman/roman_wcs.py Resolved
Comment thread galsim/roman/roman_wcs.py Resolved
Comment thread galsim/roman/roman_wcs.py Resolved
Comment thread galsim/image.py

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for these changes - I thought when I was using the functions last time that I would take all the meta information with it, didn't realize that wasn't explicitly happening

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a reasonable assumption. Which is why I changed the default. In my review it didn't occur to me that it wouldn't keep the pixel scale. That's a sign of bad API design.

Comment thread tests/test_roman.py

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I gave this a cursory look, but I'm glad the STPSF test is in here. This looks like a very comprehensive update, thanks for working this out Mike!

rmjarvis and others added 3 commits November 19, 2026 14:14
Fix positive/negative docs, which still had the old SCA orientations.

Co-authored-by: Nihar Dalal <140463192+nihardalal@users.noreply.github.com>
Co-authored-by: Mike Jarvis <michael@jarvis.net>
@FedericoBerlfein

FedericoBerlfein commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Thanks for the detailed PR Mike! I have been doing comparisons with STPSF and PSFSim, and I think there might still be a sign flip missing in the pupil mask in galsim. Let me elaborate:

While comparing this branch with STPSF 2.3.1 and PSFSim, I found that the PSF's strut pattern is mirrored up–down relative to both. The cause seems to be the orientation of the pupil files in share/roman, not the galsims internal machinery. The branch handles the pupil exactly the way STPSF does, with the the stored mask and Zernikes in one frame, then a 180 degree rotation. That is why when you pass the galsim files to STPSF, the agreement is very good. But I think the problem is that the pupil masks themselves are the up–down mirror of the masks STPSF uses (in Cycle 10) and the ones PSFSim makes. The plot below shows this, the first column is the STPSF pupil mask as given by STPSF currently. The second column is the one stored in galsim right now. The third column shows them superimposed, with the differences in their overlay in blue and orange. The last column shows the same overlay if we do an up-down flip of the galsim pupil.
Screenshot 2026-11-20 at 12 23 49 AM

This seems to suggest that the up-down flip that Nihar had added previously was the correct flip to the pupil currently in galsim. The problem might be that the pupil mask and the zernikes were not in the same frame in Cycle 9, and that the flip was necessary to do get them in the same frame. Maybe this was fixed in Cycle 10 and the pupil mask and zernikes were now in the same frame.
The next plot shows an image of the monochromatic PSF for F184, with the angles of the split diffraction spike shown in white (~70 degrees) and green (~110 degrees). You can see that the split diffraction lies at different angles between the galsim PR and STPSF, exactly corresponding to an up-down flip. The bottom plot shows the same result but in a 1D plot similar to the one you showed above.

Screenshot 2026-11-20 at 12 28 20 AM Screenshot 2026-11-20 at 12 27 51 AM

So I think the the existing tests passes in tests/roman_files/generate_stpsf_psfs.py because it makes the STPSF reference images by loading galsim's own pupil files into STPSF, along with the Cycle 9 table. So the tests confirm that the propagation and conventions match STPSF's. Because both sides read the same file, they can't detect a mirrored file. So I think the issue is just with the pupil mask in Cycle 9 being flipped compared to the current one used in STPSF.

Here is a galsim_pr_pupil_orientation.py that you can use to replicate the results.

…pply the flip they now do directly to the file
@rmjarvis

rmjarvis commented Nov 20, 2026 •

Copy link
Copy Markdown
Member Author

Interesting. I intentionally scoped this so far to stick to the Cycle 9 inputs rather than update the input files yet to try to identify code differences rather than reference file issues.

I updated the generate script to use roman's original reference files from cycle 9 rather than the ones we copied into galsim, and the old orientation is there. (This is their 2.0.0 data.) So the change in the reference pupil's orientation happened after that. Of course, that also means that using the new STPSF code with the old reference files is probably wrong. But I'm not sure where the aberrations fit into that. I.e. when to have STPSF flip the pupil plane when using the old files -- before or after applying the aberrations.

I have another branch where I've started updating the GalSim reference files to Cycle 10 and later, so that will be a more definitive test that we match current STPSF for both code and reference files. For now I've put a y flip in the generator script before applying aberrations. I think I found evidence that this is right from historical stpsf code, but it's hard to say for sure. I think I won't be fully confident in this choice until I finish updating everything to the current reference files.

And I re-added the flip_ud line in GalSim to match this treatment. Thanks for catching this Federico!

@nihardalal

Copy link
Copy Markdown
Contributor

We can discuss this more on the PSF call today, but I can concur that old versions of STPSF had an inconsistent sign treatment, but I think the project (and especially Tim Brandt) seem confident that whatever in STPSF 2.3.1 matches the real data pretty well. I think a useful task would be to dig through the STPSF release notes and document exactly which flips were made when

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug report Bug report roman Relevant to Roman Space Telescope specifically, especially including the galsim.roman module.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants